IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/perl5/Benchmark.z/Benchmark

Text File | 2002-10-03 | 10.2 KB | 331 lines

BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))



NNNNAAAAMMMMEEEE
     Benchmark - benchmark running times of code

     timethis - run a chunk of code several times

     timethese - run several chunks of code several times

     timeit - run a chunk of code and see how long it goes

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
         timethis ($count, "code");

         # Use Perl code in strings...
         timethese($count, {
             'Name1' => '...code1...',
             'Name2' => '...code2...',
         });

         # ... or use subroutine references.
         timethese($count, {
             'Name1' => sub { ...code1... },
             'Name2' => sub { ...code2... },
         });

         $t = timeit($count, '...other code...')
         print "$count loops of other code took:",timestr($t),"\n";


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The Benchmark module encapsulates a number of routines to help you figure
     out how long it takes to execute some code.

     MMMMeeeetttthhhhooooddddssss

     new       Returns the current time.   Example:

                   use Benchmark;
                   $t0 = new Benchmark;
                   # ... your code here ...
                   $t1 = new Benchmark;
                   $td = timediff($t1, $t0);
                   print "the code took:",timestr($td),"\n";


     debug     Enables or disable debugging by setting the $Benchmark::Debug
               flag:

                   debug Benchmark 1;
                   $t = timeit(10, ' 5 ** $Global ');
                   debug Benchmark 0;





                                                                        PPPPaaaaggggeeee 1111






BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))



     SSSSttttaaaannnnddddaaaarrrrdddd EEEExxxxppppoooorrrrttttssss

     The following routines will be exported into your namespace if you use
     the Benchmark module:

     timeit(COUNT, CODE)
               Arguments: COUNT is the number of times to run the loop, and
               CODE is the code to run.  CODE may be either a code reference
               or a string to be eval'd; either way it will be run in the
               caller's package.

               Returns: a Benchmark object.

     timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )
               Time COUNT iterations of CODE. CODE may be a string to eval or
               a code reference; either way the CODE will run in the caller's
               package.  Results will be printed to STDOUT as TITLE followed
               by the times.  TITLE defaults to "timethis COUNT" if none is
               provided. STYLE determines the format of the output, as
               described for _t_i_m_e_s_t_r() below.

               The COUNT can be zero or negative: this means the _m_i_n_i_m_u_m
               _n_u_m_b_e_r _o_f _C_P_U _s_e_c_o_n_d_s to run.  A zero signifies the default of
               3 seconds.  For example to run at least for 10 seconds:

                       timethis(-10, $code)

               or to run two pieces of code tests for at least 3 seconds:

                       timethese(0, { test1 => '...', test2 => '...'})

               CPU seconds is, in UNIX terms, the user time plus the system
               time of the process itself, as opposed to the real (wallclock)
               time and the time spent by the child processes.  Less than 0.1
               seconds is not accepted (-0.01 as the count, for example, will
               cause a fatal runtime exception).

               Note that the CPU seconds is the mmmmiiiinnnniiiimmmmuuuummmm time: CPU scheduling
               and other operating system factors may complicate the attempt
               so that a little bit more time is spent.  The benchmark output
               will, however, also tell the number of $code runs/second, which
               should be a more interesting number than the actually spent
               seconds.

               Returns a Benchmark object.

     timethese ( COUNT, CODEHASHREF, [ STYLE ] )
               The CODEHASHREF is a reference to a hash containing names as
               keys and either a string to eval or a code reference for each
               value.  For each (KEY, VALUE) pair in the CODEHASHREF, this
               routine will call




                                                                        PPPPaaaaggggeeee 2222






BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))



                       timethis(COUNT, VALUE, KEY, STYLE)

               The routines are called in string comparison order of KEY.

               The COUNT can be zero or negative, see _t_i_m_e_t_h_i_s().

     timediff ( T1, T2 )
               Returns the difference between two Benchmark times as a
               Benchmark object suitable for passing to _t_i_m_e_s_t_r().

     timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )
               Returns a string that formats the times in the TIMEDIFF object
               in the requested STYLE. TIMEDIFF is expected to be a Benchmark
               object similar to that returned by _t_i_m_e_d_i_f_f().

               STYLE can be any of 'all', 'noc', 'nop' or 'auto'. 'all' shows
               each of the 5 times available ('wallclock' time, user time,
               system time, user time of children, and system time of
               children). 'noc' shows all except the two children times. 'nop'
               shows only wallclock and the two children times. 'auto' (the
               default) will act as 'all' unless the children times are both
               zero, in which case it acts as 'noc'.

               FORMAT is the the _p_r_i_n_t_f(_3) manpage-style format specifier
               (without the leading '%') to use to print the times. It
               defaults to '5.2f'.

     OOOOppppttttiiiioooonnnnaaaallll EEEExxxxppppoooorrrrttttssss

     The following routines will be exported into your namespace if you
     specifically ask that they be imported:

     clearcache ( COUNT )
               Clear the cached time for COUNT rounds of the null loop.

     clearallcache ( )
               Clear all cached times.

     disablecache ( )
               Disable caching of timings for the null loop. This will force
               Benchmark to recalculate these timings for each new piece of
               code timed.

     enablecache ( )
               Enable caching of timings for the null loop. The time taken for
               COUNT rounds of the null loop will be calculated only once for
               each different COUNT used.

NNNNOOOOTTTTEEEESSSS
     The data is stored as a list of values from the time and times functions:





                                                                        PPPPaaaaggggeeee 3333






BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))



           ($real, $user, $system, $children_user, $children_system)

     in seconds for the whole loop (not divided by the number of rounds).

     The timing is done using _t_i_m_e(3) and _t_i_m_e_s(3).

     Code is executed in the caller's package.

     The time of the null loop (a loop with the same number of rounds but
     empty loop body) is subtracted from the time of the real loop.

     The null loop times are cached, the key being the number of rounds. The
     caching can be controlled using calls like these:

         clearcache($key);
         clearallcache();

         disablecache();
         enablecache();


IIIINNNNHHHHEEEERRRRIIIITTTTAAAANNNNCCCCEEEE
     Benchmark inherits from no other class, except of course for Exporter.

CCCCAAAAVVVVEEEEAAAATTTTSSSS
     Comparing eval'd strings with code references will give you inaccurate
     results: a code reference will show a slower execution time than the
     equivalent eval'd string.

     The real time timing is done using _t_i_m_e(2) and the granularity is
     therefore only one second.

     Short tests may produce negative figures because perl can appear to take
     longer to execute the empty loop than a short test; try:

         timethis(100,'1');

     The system time of the null loop might be slightly more than the system
     time of the loop with the actual code and therefore the difference might
     end up being < 0.

AAAAUUUUTTTTHHHHOOOORRRRSSSS
     Jarkko Hietaniemi <_j_h_i@_i_k_i._f_i>, Tim Bunce <_T_i_m._B_u_n_c_e@_i_g._c_o._u_k>

MMMMOOOODDDDIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN HHHHIIIISSSSTTTTOOOORRRRYYYY
     September 8th, 1994; by Tim Bunce.

     March 28th, 1997; by Hugo van der Sanden: added support for code
     references and the already documented 'debug' method; revamped
     documentation.





                                                                        PPPPaaaaggggeeee 4444






BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))



     April 04-07th, 1997: by Jarkko Hietaniemi, added the run-for-some-time
     functionality.





















































                                                                        PPPPaaaaggggeeee 5555